<html>
<head>
    <title>Twenty Second Tutorial</title>
</head>
<body>

<p>There is one main factory class in EasierMock called <strong><a href="apidocs/org/easiermock/EasierMock.html">EasierMock</a></strong></p>


<p><strong>Note:</strong> All EasierMock classes are in the
    <strong><code>org.easiermock</code></strong> package.</p>

<h1>Step By Step</h1>

<p>An EasierMock is made up of a mock or stub class that you (the developer) writes and some dynamically generated code that EasierMock provides. For the purposes of this tutorial the developer-written class will be referred to as the "delegate", the class being mocked will be called the "real class" and the mock object (generated by EasierMock) will be called the "mock". The role of EasierMock is to take the developer's delegate object and provide a mock class that provides the same interface as the real class. There does not have to be any class-hierarchy relationship between the delegate class and the real class, though as will be explained, it may help to you if there is. EasierMock looks for an annotation (@Mock) to determine which methods called on the mock object should be passed on to the delegate. Calls to methods that are not marked with @Mock will throw an UnsupportedOperationException.</p>

<p>A basic delegate class might look like this:</p>

<pre>
public interface MyReal {
  public void method1();
  public void method2();
}

public class MyMock implements MyReal {
  @Mock
  public void method1() {
    // This is mocked - it is annotated with @Mock
  }

  public void method2() {
    // This is not mocked (there is no @Mock annotation)
    // Calls to this method will not be passed on and will result in an UnsupportedOperationException.
  }
}
</pre>

<h1>Should the delegate implement the same interface/extend from the real class?</h1>

<p>There <em>does not</em> need to be a class-hierarchy relationship between the delegate and the real class. EasierMock works via reflection so the only requirement is that the methods on the delegate have the same signature as those declared on the real class. Even though this is the case developers will often find it easier to extend or implement the real class when writing the delegate as this will assist when using refactoring tools to ensure that the signature of the delegate is refactored along with the mock.</p>

<h2>Real interfaces: Implementing the interface with the delegate</h2>

<p>When the real class is an interface and the delegate implements the interface there is no option for the developer but to provide empty/no-op implementations of the entire interface. Developers can choose to mark all methods as being mocked or not. Any methods that are not marked with @Mock will throw UnsupportedOperationException unless the class itself is marked with @Mock (which indicates that <em>all</em> declared methods on the class are mock implementations). Tools such as IntelliJ provide the ability to generate a class that throws UnsupportedOperationException, so if you are using this tool or something similar, you may find it easiest to mark the entire class with @Mock rather than only annotating the methods you have provided mock implementations for.</p>

<p>E.g.:</p>

<pre>
@Mock
public class MyDelegate implements MyReal {
  public void method1() {
    // Your mock method here
  }

  public void method2() {
    throw new UnsupportedOperationException();
  }
}
</pre>

<h2>Real interface: Not implementing the interface with the delegate</h2>

<p>Not implementing the interface with the delegate is potentially much less code (depending on the size of the interface being mocked). However, it suffers from the disadvantage already mentioned that refactoring could break your tests. While this should be fairly easy to spot when it happens (since your tests should break), it does mean a maintenance overhead.</p>

<p>Here is the same example as above but without the inheritence:</p>

<pre>
public class MyDelegate {
  @Mock
  public void method1() {
    // Your mock method here
  }
}
</pre>

<h2>Real class: Extending the Real with the delegate</h2>

<p>This case is where EasierMock really starts pulling its weight. Let's take the example of wanting to have a mock implementation of the java.io.File class. Here you can just extend and only implement the methods you intend to mock:</p>

<pre>
public class MockFile extends File {
  public MockFile() {
    super("MockFile");
  }

  @Mock
  public String getParent() {
    // Your mock method here
  }
}
</pre>

<p>All other methods receive the standard EasierMock treatment of throwing UnsupportedOperationException.</p>

<h2>Real class: Not extending the Real with the delegate</h2>

<p>This option is largely the same as with interfaces. It has the same advantages and disadvantages, except that you may find cases where you <em>cannot</em> extend the real class due to language restrictions and so you are forced to do it (e.g. if the real class does not have a public constructor). EasierMock does not have the same restrictions as classes you write so it <em>can</em> extend from these classes (though not final classes, etc.).</p>

<h1>The EasierMock API</h1>

<p>Creating a mock is a simple call to a static method. The developer provides the delegate and the class to be mocked.</p>

<pre>
MyDelegate delegate = new MyDelegate();
MyReal mockReal = EasierMock.createMock(MyReal.class, delegate);
</pre>

<p>The mockReal variable can be used in your tests in place of the real.</p>

<h1>Other features of EasierMock</h1>

<p>EasierMock provides an additional mechanism to help developers avoid writing tedious boilerplate code. Quite often, you will want your delegate class to tell you whether a method has been called or how many times it was called. The other mock framework called EasyMock (that EasierMock is designed to work alongside) provides the EasyMock.expect() method to combine the method counting with test expectations. While this is very elegant, many people find it hard to use. EasierMock provides a class called CountingMethodListener which keeps a count that is incremented before a mock method is called.</p>

<pre>
CountingMethodListener methodCounter = new CountingMethodListener();
MyDelegate delegate = new MyDelegate();
MyReal mockReal = EasierMock.createMock(MyReal.class, delegate, methodCounter);
</pre>

<p>In tests, the CountingMethodListener can be queried to determine the number of calls that have been made to a method</p>

<pre>
assertEquals(5, methodCounter.getBeforeCount("methodId"));
</pre>

<p>There is one piece of the puzzle missing: Where does the string "methodId" come from? It can be specified as an optional part of the Mock annotation:</p>

<pre>
public class MyDelegate {
  @Mock(id="methodId")
  public void method1() {
    // Your mock method here
  }
}
</pre>

<p>If you do not specify the ID with the annotation, the name of the method is used instead.</p>
<p>If a method is overloaded, or if the same ID is specified for multiple methods there is a single counter that is incremented when any of those methods are called.</p>
<p>A listener can be shared across multiple mocks.</p>
<p>Tip: The id attribute can be specified as a final static String in test code which makes it easy to maintain.</p>

<p>EasierMock doesn't provide any more than basic method invocation counting because existing frameworks like EasyMock already provide a lot of the more complex behaviour one would want beyond this. However, there is nothing to stop developers from writing more complicated implementations of MethodListener.</p>

</body>
</html>